JavaPureCheck is a checker that inspects a Java program for portability problems. It discovers potential problems that your program might encounter when running on a different implementation of the Java platform. JavaPureCheck is developed as a part of the 100% Pure Java Certification Program.
JavaPureCheck is a product of SunTest; for more information about testing solutions for Java, see our Web page at http://www.suntest.com.
JavaPureCheck checks specified classes against a rule base that defines portability concerns. Any class that does not meet these rules is flagged with the specific portability problem found. You can review these errors and add explanations of your own. These errors and explanations are kept in a database that allows you to produce reports of portability problems for later review or consultation.
|
|
Note: If you want to learn more about the rule base and types of checks, JavaPureCheck allows you to generate the documentation on the rule model. See Documentation of Rules and Error Messages. |
While useful in its own right, JavaPureCheck is also an integral part of the 100% Pure Java validation process (see http://java.sun.com/100percent. )
This version of JavaPureCheck, version 2.1, is a production release. This production release may be used when preparing a program for 100% Pure Java validation submission. If you encounter bugs or performance problems, or have suggestions for enhancement, please report them via the Web at URL http://www.suntest.com/100percent.
JavaPureCheck, version 2.1, contains the following new features:
Class.for.Name is now flagged with a warning
To run JavaPureCheck, you must have a Java virtual machine and class library, version 1.1 or later. The program was developed using JDK 1.1.1.
Once you have extracted it from the distribution file, JavaPureCheck resides in a subdirectory named cpd with this structure:
cpd/
javapurecheck.txt
tools/
javapurecheck.jar -- Classes and resources required
to run JavaPureCheck are bundled
into a single JAR file.
doc/tools/index.html -- this documentation
Add <install_dir>/cpd/tools/javapurecheck.jar
to the CLASSPATH. Refer to the Java documentation for your
installation to find out how to set the CLASSPATH.
JavaPureCheck does static checking of your program (i.e., your program never gets executed). You need not put the program you are checking in the CLASSPATH to run JavaPureCheck. JavaPureCheck reads your class file(s) as input.
Type this command from the command line to run a visual version of JavaPureCheck.
You will see a flash screen. To view the flash screen again at any time, click on the 100% Pure Java Logo in the JavaPureCheck window.
The visual version of JavaPureCheck will guide you through the process by enabling and disabling buttons on the side bar. The arrow to the left of the button shows you which step you are working on. There are three main steps as described below:
The system model (rule base) determines which criteria your classes are checked against. A system model is a list of the names defined in a version of the Java Core API, annotated with portability information, used to check your program. You can find out exactly what is in a system model (rule base) by generating and reading the HTML documentation for the model (see A Report of Rules ).
To set the model, click on the button next to the version of Java to which your program will comply. The default model is jdk102 .
|
|
Note: jdk11 is a model for all versions of JDK 1.1.x. |
You can set the name of your output report file and explanations database in the Report Filename field. The report is produced in the directory from which the tool is invoked (in this example, from Windows it is C:\ ). The default name is results.jpc . The same directory and filename are used to derive the name of the explanations database with the extension <filename>EXP.ser (i.e., resultsEXP.ser).
You can place the output in another filename or directory by specifying an absolute path or a path relative to the directory seen in the title bar. If you specify an extension other than .jpc , JavaPureCheck creates a file by that name and appends .jpc and EXP.ser to the end of that name. For example, if you specified a:\run1 as the filename, your report is generated as a:\run1.jpc and the explanations are in a:\run1EXP.ser .
You can specify any combination of classes, directories, ZIP or JAR files to tell JavaPureCheck which classes to check.
You directly specify a directory or class by typing its path relative to the current directory seen in the title bar. Then press Enter or click on the Add button below the text field. If JavaPureCheck can locate the input, its name appears in the list below. If not, you will get a pop-up dialog informing you that your entry was invalid.
When you specify a directory, JavaPureCheck checks all classes included in that directory and all classes included in sub-directories of that directory.
Alternatively, you may browse to locate a class. Click on the Browse button and locate the exact class you wish to add.
|
|
Note: Due to a limitation of the Java API, on certain window managers (e.g., Windows95), it is not possible to use the browser to select a directory. |
If you explicitly specify a class and the directory containing that class, JavaPureCheck checks the class twice.
All the class files that you specify for one run of JavaPureCheck are considered as a program set. An incomplete program set (one with unsatisfied references) is considered as a whole to be impure, as that is the most conservative estimate of the missing class files. JavaPureCheck still produces detailed information about each class file checked, thereby providing you with the means to identify the purity of the classes in the program set.
You can delete an item from the input list by selecting it and clicking on Delete.
When you are done specifying the input to JavaPureCheck, start the checking process by clicking the Check button. JavaPureCheck loads the system model and checks all the class files you specified as input.
A progress bar and progress counters show you the status of the check as it runs, and a window shows you the name of each input class as it is checked. The progress bar color reflects the deepest level of error (green if pure, yellow if warnings, or red if errors have been found). You can click on the Abort button to cancel the check. Here is an example of what the JavaPureCheck screen looks like during the check phase: .
After the check run is complete, you can switch to the analyze window to inspect and explain the results. This is the analyze window.
The analyze window shows a list of the checked classes; check the appropriate boxes at the top of the window to filter the results based on severity.
In the center of the window is a scrolling list of the checked classes, with an indication of their purity status. Click the Details button to view the errors and enter explanations for classes with portability problems. Once you have entered the explanations, the Details button will change to read Explained.
The explanation window shows all the problems found when inspecting one class. When a problem is selected, the Note pane shows the element in the program identified as a portability problem. (The 100% Pure Java Cookbook can be consulted for full information on portability problems, workarounds and solutions.) The Explanation pane shows the explanation (if any) you have provided for the selected problem. You can insert or replace the explanation for a particular problem by editing the text in the explanation pane.
Any explanations you enter are saved in a database with the name specified as Report Filename in the input window (see Report Filename: Where to put reports? ). This database is saved when you explicitly click Commit or close the explanation window. When you commit, you commit all changes made to the database for any class represented in that database, not just those which you can currently view in an explanation window. You can save the database as often as you like; your explanations are added to the database file when you commit.
You can replace an explanation by selecting it and editing; the new version is saved when you commit. The explanation window only shows the explanations for errors reported in the latest check.
The explanations database has all the explanations you have provided for a program set. The database is reloaded when JavaPureCheck is run again, so that your explanations are preserved across checks. Explanations remain even when you delete and add classes to the input list, as long as the name of the class does not change.
You can use JavaPureCheck directly from the command line without using the GUI. The syntax is:
java JavaPureCheck -d systemModelName classFile...
where systemModelName is the name of the system model to verify against (either jdk11 or jdk102 ).
The report is written to results.jpc, by default. You can direct it to another file by using this switch:
-o reportFile
The command-line version uses much less memory than the GUI version. This makes it useful for checking very large programs. However, there is no way to attach explanations using the command-line version besides manually editing the report.
 |
Caution: The report produced by JavaPureCheck in batch mode is not the same as the report produced in GUI mode. In particular, classes with undefined references are not marked as "ERROR" in the body of the batch-mode report; instead, all information about undefined references is shown at the bottom of the report. |
The report file written by JavaPureCheck lists each class checked, it's status, and a report on any portability problem found. The report shows any problem explanations which you have committed to the explanations database using the GUI version. Here is a sample report:
JavaPureCheck report Generated at May 1, 1997 4:02:31 PM PDT System model: "JDK 1.0 model version 1.3" Rule base version: 1.35 Class: Calc Status: PURE Class: CalcApplet Warning: possible hard-coded path: "/" Explanation: This is the name of a button. Status: WARNING Undefined classes: Final result: WARNING |
JavaPureCheck can write, in HTML format, a detailed list of the rules used to check your program. The command to do so is:
java JavaPureCheck -dsystemModelName-h
where systemModelName is the name of the system model to list (either jdk11 or jdk102 ). The report is generated under the current directory bearing the name systemModelName.html (i.e., jdk102.html ).
The rules for the current version of JavaPureCheck are:
Copyright 1997, Sun Microsystems
